Skip to content

v1 Mantis: one arm for v3 and v4, moved in the deck frame, guarded, with zone routes and approach paths - #1631

Open
BioCam wants to merge 10 commits into
mainfrom
mantis-v1-04-arm-moves
Open

BioCam wants to merge 10 commits into
mainfrom
mantis-v1-04-arm-moves

Conversation

@BioCam

@BioCam BioCam commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

The Problem

The Mantis could bring its arm up and stop it, but not move it. A move has to be given in PyLabRobot's deck frame, where wells are, while the arm is a five-bar linkage calibrated per unit, with a tilted stage. A move across the deck must first clear what stands on it, and from anywhere (any zone, the waste, a wash) the arm needs a safe way back to idle. Main meanwhile gained a separate v3 arm and clamp, so two classes each would have stood side by side.

PR Content/Solution

How a move works:

flowchart TD
  A["move_to_location(well)"] --> B["well in the deck frame"]
  B --> C["arm frame: the unit's calibration"]
  C --> D["two arm angles + Z"]
  D --> E{"Z low?"}
  E -- yes --> F["raise Z, read it back"]
  F --> G["arms across, then Z down"]
  E -- no --> G
Loading

Where the arm can go, and how it gets home:

flowchart TD
  Z["anywhere on the deck"] -- "park(): the zone's route" --> I(("idle"))
  I -- "move_to_location()" --> P["wellplate"]
  I -- "move_to_waste()" --> W["waste"]
  I -- "move_to_wash()" --> X["wash 1 or 2"]
  W -- "leave: arms first, then Z" --> I
  X -- "leave: arms first, then Z" --> I
Loading

Usage

Every snippet ran top to bottom in simulation on this head.

from pylabrobot.formulatrix import Mantis
from pylabrobot.resources import Coordinate
from pylabrobot.resources.corning import cor_96_wellplate_360uL_Fb

mantis = Mantis(name="mantis", oem_config_directory="…")  # the unit's configuration folder
await mantis.setup()

wellplate = cor_96_wellplate_360uL_Fb(name="wellplate")
mantis.plate_holder.assign_child_resource(wellplate)

# to a well, 12.5 mm above it
a1 = wellplate.get_well("A1").get_location_wrt(mantis.deck, x="c", y="c", z="t")
await mantis.arm.move_to_location(location=a1 + Coordinate(z=12.5))

# across with a low traverse height (Z rises to it only if below it), then down
h12 = wellplate.get_well("H12").get_location_wrt(mantis.deck, x="c", y="c", z="t")
await mantis.arm.move_to_xy_position(x=h12.x, y=h12.y, minimum_traverse_height_start=h12.z + 5)
await mantis.arm.move_to_z_position(z=h12.z + 2.5)

# the waste and the washes, from wherever the head stands; then home
await mantis.arm.move_to_waste()
await mantis.arm.move_to_wash(position=1)  # out of the waste, into wash 1
await mantis.arm.move_to_wash(position=2)  # across, inside the wash
await mantis.arm.park()  # out along wash 2's path, then to idle

pose = await mantis.arm.request_pose()  # elbows, head and nozzle in the deck frame
pose.nozzle_location  # Coordinate, mm

mantis.arm.default_xy_speed = 50.0  # mm/s at the nozzle
mantis.arm.default_z_speed = 60.0  # ValueError: default_z_speed must be from 1.0 to 55.0, got 60.0

center = mantis.plate_holder.get_location_wrt(mantis.deck, x="c", y="c")
mantis.arm.is_xy_reachable(x=center.x, y=center.y)  # True; nothing is sent

Features

  • One Arm and one PlateClamp on v3 and v4, with the same public methods; the generation picks only private plumbing. A v4 reads where it is from its absolute encoders, a v3 homes on its flags; a v3's moves after bring-up raise NotImplementedError until a v3 has run them. A v4 is never taken for a v3.
  • Guarded, as v1 STAR: before any move across, Z rises to the traverse height if below it and is read back.
  • Safe exits: leaving the waste or a wash, the arms go back first with Z held, then Z rises; Z alone is refused on a path; a cancelled or timed-out move stops every motor.
  • Speeds in mm/s, range-checked when set; scaled per motor so both arm motors end together; accelerations are never scaled down.
  • Typed frames: deck positions are PLR Coordinates, the unit's own frame is MantisArmCoordinate.
  • Plate clamp: "clamping done" means the lock's timer ran out, not that a plate is held.
  • Also: the arm's links drawn from the manufacturer's meshes; MantisPose and MantisArmConfiguration in docs/api; everything runs on Mantis(simulation=True).

On the device

A Mantis v4, head clear, no chip:

result
bring-up, refusals, guard, waste and washes, stop(), recovery all passed; the only differences from the previous run are the intended ones
setup() from all six zones back to idle within 3·10⁻⁸ device units, RightBack included
four corners of a wellplate, with a plate arm targets bit for bit the computed ones; Z up and read back before every move across
plate clamp, every level, with and without a plate same states, same times

One defect: with only an xy speed given, a barely-turning motor got a scaled-down acceleration that the device refused; the run stopped safely. Fixed (accelerations are never scaled down) and covered by tests, not yet re-run on the device. Moves on a v3 after bring-up have not run on a v3.

Follow-ups: move_to_xy_position and move_to_location can differ by one floating-point bit; nine tests still cut every reply timeout to 0.25 s.

🤖 Generated with Claude Code

…s and approach paths

The arm's configuration on mantis.arm.configuration; moves in the deck frame through the unit's
stage transform, each move across guarded by a rise to the traverse height; speeds in mm/s at the
nozzle; park and recovery along each zone's route; move_to_waste and move_to_wash from wherever
the head stands; request_pose for every joint in the deck frame.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@BioCam
BioCam force-pushed the mantis-v1-04-arm-moves branch from f98893f to e6234df Compare November 13, 2026 20:24
BioCam and others added 9 commits November 16, 2026 09:58
…nd LC3 carousel

V3Arm takes the arm's configuration and the approved v3_arm_configuration, reads through
request_joint_state and request_pose, and refuses every move after the bring-up until a v3 has
run it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Each link's mesh, in mm and in the link's own frame, is declared in manifest.json and attached by
arm_link, as the chip racks and the Z column are.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Board 11 gets a second attempt before its silence makes a unit a v3, and an arm block with
absolute-encoder references refuses the v3 path, so a v4's arms are never seated against their
stops.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The v3 arm and pneumatic clamp become private plumbing of Arm and PlateClamp, picked by the
generation in listed fork points. The v3 bring-up sends the same bytes; where the arms are is read
from a v4's absolute encoders or a v3's homed motor positions, and moves on a v3 stay refused until
a v3 has run them.

Co-Authored-By: Rick Wierenga <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
…le in the deck frame

Route lines, approach paths, zone routes, the post-homing position and the kinematics' positions
are MantisArmCoordinate, never a PLR Coordinate; _get_arm_frame_location and
_get_deck_frame_location convert between the two over the unrounded float helpers, so what is sent
is unchanged.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
… in text

- Leaving the waste or a wash, the arms go back first with Z held, then Z rises, never both at depth.
- Arguments are checked before the head leaves an approach path; Z alone is refused on one.
- A queued move that times out or is cancelled is aborted and every motor stopped.
- An xy speed or acceleration given alone still ends both arm motors together.
- MantisPose and MantisArmConfiguration in docs/api; the notebook's arm cells run in simulation.
- The clamp's 'clamping done' means its timer ran out, not that a plate is held.
- Messages show mm and degrees with 2 decimals; nothing sent is rounded.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…e queue

Python before 3.12 can drop a cancellation that races a reply inside asyncio.wait_for, so the test
cancelled as 0/68's reply arrived and the move then timed out on 3.10 and 3.11.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The device refused a queued move whose barely-turning motor got a scaled acceleration of 18.2 device
units/s² (error 6). Speeds stay scaled per motor by turn; both motors take the route's acceleration,
or the given one as the motor that turns most needs it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…motor-error test

The test cut every command's reply timeout to 0.25 s for the one command never answered, so a slow
CI runner timed out an answered one (0/17).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@BioCam BioCam changed the title v1 Mantis: move the arm in the deck frame, guarded, with zone routes and approach paths v1 Mantis: one arm for v3 and v4, moved in the deck frame, guarded, with zone routes and approach paths Nov 16, 2026
@BioCam
BioCam marked this pull request as ready for review November 17, 2026 09:58
@BioCam
BioCam requested a review from a team as a code owner November 17, 2026 09:58

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant